<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Genedex</title>
<meta name="author" content="Brent Pedersen" />
<style type="text/css">

div.highlight {
    margin-left: 2em ;
    border: 1px solid #cccccc;
    margin-right: 2em ;
    background-color: #eeeedd;
    font-family: "Courier New", Courier, monospace;
    font-size: 10pt;
}

</style>
</head>
<body>
<div class="document" id="genedex">
<h1 class="title">Genedex</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr class="field"><th class="docinfo-name">Description:</th><td class="field-body">Simple, efficient queries and sequence-retrieval of genomic features.</td>
</tr>
<tr><th class="docinfo-name">Author:</th>
<td>Brent Pedersen</td></tr>
<tr class="field"><th class="docinfo-name">Email:</th><td class="field-body"><a class="reference external" href="mailto:bpederse&#64;gmail.com">bpederse&#64;gmail.com</a></td>
</tr>
<tr class="field"><th class="docinfo-name">License:</th><td class="field-body">LGPL</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#features" id="id3">Features</a></li>
<li><a class="reference internal" href="#fasta" id="id4">Fasta</a></li>
<li><a class="reference internal" href="#queries" id="id5">Queries</a><ul>
<li><a class="reference internal" href="#methods" id="id6">Methods</a><ul>
<li><a class="reference internal" href="#distance" id="id7">distance</a></li>
<li><a class="reference internal" href="#intersection" id="id8">intersection</a></li>
<li><a class="reference internal" href="#nearest" id="id9">nearest</a></li>
<li><a class="reference internal" href="#neighbors" id="id10">neighbors</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#id2" id="id11">Genedex</a><ul>
<li><a class="reference internal" href="#creation" id="id12">Creation</a></li>
<li><a class="reference internal" href="#query" id="id13">Query</a></li>
<li><a class="reference internal" href="#exons" id="id14">Exons</a></li>
</ul>
</li>
<li><a class="reference internal" href="#bugs" id="id15">Bugs</a></li>
<li><a class="reference internal" href="#todo" id="id16">TODO</a></li>
</ul>
</div>
<div class="section" id="features">
<h1><a class="toc-backref" href="#id3">Features</a></h1>
<p>Genedex uses the simplest possible representation of genomic features,
a python dictionary.  At the minimum, a feature must have a 'start'
and a 'stop' attribute. This is a valid feature:</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> feature <span style="color: #666666">=</span> {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">12</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">19</span>}
</pre></div>
<p>To take full advantage of the features of genedex, a feature should
also have a 'strand' of either 1 or -1. Any other arbitrary key-value
pairs in the dictionary are allowed.</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> feature <span style="color: #666666">=</span> {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">12</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">19</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>, <span style="color: #BA2121">&#39;name&#39;</span>:<span style="color: #BA2121">&#39;At2g26540&#39;</span>}
</pre></div>
<p>A useful attribute to add is exons, for a single feature with many
start/stop positions. This can be used by genedex for sequence
extraction as described later:</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> feature <span style="color: #666666">=</span> {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">12</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">19</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>, <span style="color: #BA2121">&#39;name&#39;</span>: <span style="color: #BA2121">&#39;At2g26540&#39;</span>
<span style="color: #666666">...</span>           , <span style="color: #BA2121">&#39;exons&#39;</span>:[(<span style="color: #666666">12</span>, <span style="color: #666666">13</span>), (<span style="color: #666666">15</span>, <span style="color: #666666">16</span>), (<span style="color: #666666">18</span>, <span style="color: #666666">19</span>)]}
</pre></div>
<p>Where 'exons' can be any name (e.g. 'mRNAs', 'CDSs', 'frankenstein', etc. ) and the value is an iterable of start, stop tuples.</p>
</div>
<div class="section" id="fasta">
<h1><a class="toc-backref" href="#id4">Fasta</a></h1>
<p>The genedex.Fasta class provides a simple interface to slicing
and retrieving genomic sequence. It uses memmaped numpy arrays for
efficient slicing and access. The first time a Fasta object is created
for a given fasta file, it will create a .gdx file that is associated
with that fasta file. The .gdx file is a pickled representation of an
index of the sequence where the keys are fasta
headers and the values are the seek() locations of the starts and
stops of the corresponding sequence. These locations are used to
tell numpy where to start and stop the memmap'ing for each chr in the
fasta file.
Given a simple fasta file, create an index and do some slicing:</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">genedex</span> <span style="color: #008000; font-weight: bold">import</span> Fasta

<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">print</span> <span style="color: #008000">open</span>(<span style="color: #BA2121">&#39;tests/data/two_chrs.fasta&#39;</span>)<span style="color: #666666">.</span>read()
<span style="color: #666666">&gt;</span> chr1
ACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTG
<span style="color: #666666">&lt;</span>BLANKLINE<span style="color: #666666">&gt;</span>
<span style="color: #666666">&lt;</span>BLANKLINE<span style="color: #666666">&gt;</span>
<span style="color: #666666">&gt;</span> chr2
TAAAAAAAAA
AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAT
<span style="color: #666666">&lt;</span>BLANKLINE<span style="color: #666666">&gt;</span>


<span style="color: #666666">&gt;&gt;&gt;</span> f <span style="color: #666666">=</span> Fasta(<span style="color: #BA2121">&#39;tests/data/two_chrs.fasta&#39;</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> sorted(f<span style="color: #666666">.</span>keys())
[<span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;chr2&#39;</span>]

<span style="color: #666666">&gt;&gt;&gt;</span> sorted(f<span style="color: #666666">.</span>index<span style="color: #666666">.</span>items())
[(<span style="color: #BA2121">&#39;chr1&#39;</span>, (<span style="color: #666666">0</span>, <span style="color: #666666">80</span>)), (<span style="color: #BA2121">&#39;chr2&#39;</span>, (<span style="color: #666666">80</span>, <span style="color: #666666">160</span>))]


<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">print</span> f[<span style="color: #BA2121">&#39;chr1&#39;</span>]
ACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTGACTG

<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">print</span> f[<span style="color: #BA2121">&#39;chr1&#39;</span>][<span style="color: #666666">2</span>:<span style="color: #666666">5</span>]
TGA
</pre></div>
<p><strong>Note</strong>: As of recent version, the fasta sequence is flattened and
index the first time it's seen, so it <strong>can</strong> contain newlines in the
sequence itself.</p>
<p>That is directly accessing the numpy array to do the slicing. A nicer
way is to use the sequence method with takes a 'feature' as described
above. If the strand is -1, it will automatically do the reverse
complement. To do the slicing, a 'chr' key with a value corresponding
to the keys in the Fasta object is required:</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> f<span style="color: #666666">.</span>sequence({<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">1</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>})
<span style="color: #BA2121">&#39;ACTGAC&#39;</span>
<span style="color: #666666">&gt;&gt;&gt;</span> f<span style="color: #666666">.</span>sequence({<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">1</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>})
<span style="color: #BA2121">&#39;GTCAGT&#39;</span>

<span style="color: #666666">&gt;&gt;&gt;</span> f<span style="color: #666666">.</span>sequence({<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">1</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}
<span style="color: #666666">...</span>            , asstring<span style="color: #666666">=</span><span style="color: #008000">False</span>)  <span style="color: #408080; font-style: italic"># doctest: +NORMALIZE_WHITESPACE</span>
array([<span style="color: #BA2121">&#39;G&#39;</span>, <span style="color: #BA2121">&#39;T&#39;</span>, <span style="color: #BA2121">&#39;C&#39;</span>, <span style="color: #BA2121">&#39;A&#39;</span>, <span style="color: #BA2121">&#39;G&#39;</span>, <span style="color: #BA2121">&#39;T&#39;</span>],
      dtype<span style="color: #666666">=</span><span style="color: #BA2121">&#39;|S1&#39;</span>)
</pre></div>
</div>
<div class="section" id="queries">
<h1><a class="toc-backref" href="#id5">Queries</a></h1>
<p>The Fasta slicing along with indexed queries is power of Genedex.
Genedex uses <a class="reference external" href="http://pypi.python.org/pypi/Rtree">rtree</a> to do fast spatial queries. To create a
persistent index send in a full path, along with a name, a .pkl file
will be created to store the features, along with .idx, .dat files
used by rtree. To overwrite an existing file, use the
overwrite=True keyword argument.</p>
<p>To add features to a genedex simply create and append:</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">genedex</span> <span style="color: #008000; font-weight: bold">import</span> Genedex
<span style="color: #666666">&gt;&gt;&gt;</span> g <span style="color: #666666">=</span> Genedex(<span style="color: #BA2121">&#39;/tmp/genedex_test&#39;</span>, overwrite<span style="color: #666666">=</span><span style="color: #008000">True</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">for</span> i <span style="color: #AA22FF; font-weight: bold">in</span> <span style="color: #008000">range</span>(<span style="color: #666666">1</span>, <span style="color: #666666">31</span>, <span style="color: #666666">5</span>):
<span style="color: #666666">...</span>     strand  <span style="color: #666666">=</span> i <span style="color: #666666">%</span> <span style="color: #666666">2</span> <span style="color: #AA22FF; font-weight: bold">and</span> <span style="color: #666666">-1</span> <span style="color: #AA22FF; font-weight: bold">or</span> <span style="color: #666666">1</span>
<span style="color: #666666">...</span>     feature <span style="color: #666666">=</span> {<span style="color: #BA2121">&#39;start&#39;</span>: i, <span style="color: #BA2121">&#39;stop&#39;</span>: i <span style="color: #666666">+</span> <span style="color: #666666">5</span>
<span style="color: #666666">...</span>             , <span style="color: #BA2121">&#39;strand&#39;</span>: strand, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>}
<span style="color: #666666">...</span>     g<span style="color: #666666">.</span>append(feature)

<span style="color: #666666">&gt;&gt;&gt;</span> g <span style="color: #408080; font-style: italic"># doctest: +ELLIPSIS</span>
<span style="color: #666666">&lt;</span>genedex<span style="color: #666666">.</span>genedex<span style="color: #666666">.</span>Genedex <span style="color: #008000">object</span> at <span style="color: #666666">0</span>x<span style="color: #666666">...&gt;</span>

<span style="color: #408080; font-style: italic"># see the first 4 features directly.</span>
<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>_store[:<span style="color: #666666">4</span>]
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">1</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">21</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}]

<span style="color: #408080; font-style: italic"># force it to save (normally happens via atexit)</span>
<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>save()
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">glob</span>
<span style="color: #666666">&gt;&gt;&gt;</span> sorted(glob<span style="color: #666666">.</span>glob(<span style="color: #BA2121">&#39;/tmp/genedex_test*&#39;</span>))
[<span style="color: #BA2121">&#39;/tmp/genedex_test.dat&#39;</span>, <span style="color: #BA2121">&#39;/tmp/genedex_test.idx&#39;</span>, <span style="color: #BA2121">&#39;/tmp/genedex_test.pkl&#39;</span>]
</pre></div>
<div class="section" id="methods">
<h2><a class="toc-backref" href="#id6">Methods</a></h2>
<p>There are really only 4 methods to know in a genedex instance:
distance(), intersection(), nearest(), and neighbors().</p>
<div class="section" id="distance">
<h3><a class="toc-backref" href="#id7">distance</a></h3>
<p>The distance method takes 2 features and returns return 0 if they
touch or overlap and the distance between their closest edges
otherwise.</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>distance({<span style="color: #BA2121">&#39;start&#39;</span>:<span style="color: #666666">2</span>, <span style="color: #BA2121">&#39;stop&#39;</span>:<span style="color: #666666">2</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>:<span style="color: #666666">4</span>, <span style="color: #BA2121">&#39;stop&#39;</span>:<span style="color: #666666">5</span>})
<span style="color: #666666">2</span>

<span style="color: #408080; font-style: italic"># or use features in the object</span>
<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>distance(g[<span style="color: #666666">2</span>], g[<span style="color: #666666">4</span>])
<span style="color: #666666">5</span>
</pre></div>
</div>
<div class="section" id="intersection">
<h3><a class="toc-backref" href="#id8">intersection</a></h3>
<p>The intersection method takes a feature and returns all features in the
genedex _store that overlap the given feature and strand.</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>intersection({<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>})
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}]

<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>intersection({<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>}, strand<span style="color: #666666">=</span>g<span style="color: #666666">.</span>MINUS)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}]

<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>intersection({<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>}, strand<span style="color: #666666">=</span>g<span style="color: #666666">.</span>PLUS)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}]
</pre></div>
</div>
<div class="section" id="nearest">
<h3><a class="toc-backref" href="#id9">nearest</a></h3>
<p>The nearest method takes a <em>feature</em> and <em>n</em>, the number of neighbors
to return. It <em>may</em> return more than the requested number of neighbors
if there are many at the same distance:</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>nearest({<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;stop&#39;</span>:<span style="color: #666666">11</span>})
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}]
<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000">len</span>(g<span style="color: #666666">.</span>nearest({<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;stop&#39;</span>:<span style="color: #666666">11</span>}, n<span style="color: #666666">=4</span>))
<span style="color: #666666">4</span>
</pre></div>
</div>
<div class="section" id="neighbors">
<h3><a class="toc-backref" href="#id10">neighbors</a></h3>
<p>The neighbors method returns the neighbors either up/downstream (or
both) of a given feature. The arguments:</p>
<pre class="literal-block">
f: a feature
n: the number of neighbors to find.
direction: -1 (upstream) or 1 (downstream), or left or right,
             available as
                 *Genedex.UP_STREAM*
                 *Genedex.DOWN_STREAM*
                 *Genedex.LEFT*
                 *Genedex.RIGHT*
           where upstream and downstream take into account the
           strand of the feature, but LEFT and RIGHT do not.
           LEFT will return features with lower basepair positions
strand: to restrict the search to a single strand, use 1/-1 available as
          *Genedex.PLUS*/*Genedex.MINUS*
          default of None searches both strands
max_dist: how far in basepairs to look before returning fewer than the
            requested number of results. note, this can override
            the n argument.
inclusive: if False, start just outside the start/stop of f
             if True, include the start/stop of f.
</pre>
<p>The inclusive is useful when using an entry in the genedex instance as
the feature but it is not wanted in the results (or vice-versa). By
default, it wont appear in the results if only a single strand is
requested. It will if no strand is specified (that may change in the
future).</p>
<div class="highlight"><pre><span style="color: #408080; font-style: italic"># get a feature.</span>
<span style="color: #666666">&gt;&gt;&gt;</span> f <span style="color: #666666">=</span> g[<span style="color: #666666">2</span>]
<span style="color: #666666">&gt;&gt;&gt;</span> f
{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}

<span style="color: #408080; font-style: italic"># use it to query...</span>
<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>neighbors(f)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">21</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}]

<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>neighbors(f, inclusive<span style="color: #666666">=</span><span style="color: #008000">True</span>)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">21</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}]

<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>neighbors(f, strand<span style="color: #666666">=</span>g<span style="color: #666666">.</span>MINUS, inclusive<span style="color: #666666">=</span><span style="color: #008000">False</span>)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">21</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">26</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">1</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}]

<span style="color: #408080; font-style: italic"># self is the closest on the MINUS strand</span>
<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>neighbors(f, strand<span style="color: #666666">=</span>g<span style="color: #666666">.</span>MINUS, inclusive<span style="color: #666666">=</span><span style="color: #008000">True</span>)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}]


<span style="color: #408080; font-style: italic"># note the default is a single neighbor, but in this case</span>
<span style="color: #408080; font-style: italic"># there were two neighbors with a distance of 0</span>
<span style="color: #666666">&gt;&gt;&gt;</span> [g<span style="color: #666666">.</span>distance(f, n) <span style="color: #008000; font-weight: bold">for</span> n <span style="color: #AA22FF; font-weight: bold">in</span> g<span style="color: #666666">.</span>neighbors(f)]
[<span style="color: #666666">0</span>, <span style="color: #666666">0</span>]


<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>neighbors(f, direction<span style="color: #666666">=</span>Genedex<span style="color: #666666">.</span>UP_STREAM)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">21</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}]

<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>neighbors(f, direction<span style="color: #666666">=</span>Genedex<span style="color: #666666">.</span>DOWN_STREAM)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">6</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}]
</pre></div>
<dl class="docutils">
<dt>since the strand is -1, downstream == left</dt>
<dd><pre class="first last doctest-block">
&gt;&gt;&gt; g.neighbors(f, direction=Genedex.DOWN_STREAM) == g.neighbors(f, direction=Genedex.LEFT)
True
</pre>
</dd>
<dt>and upstream == right</dt>
<dd><pre class="first doctest-block">
&gt;&gt;&gt; g.neighbors(f, direction=Genedex.UP_STREAM) == g.neighbors(f, direction=Genedex.RIGHT)
True
</pre>
<pre class="last doctest-block">
&gt;&gt;&gt; g.neighbors(f, direction=Genedex.DOWN_STREAM, strand=g.MINUS)
[{'start': 1, 'chr': 'chr1', 'stop': 6, 'strand': -1}]
</pre>
</dd>
</dl>
</div>
</div>
</div>
<div class="section" id="id2">
<h1><a class="toc-backref" href="#id11">Genedex</a></h1>
<p>The sections above demonstrate the use of the querying and the
sequence retrieval separately. These can be used together quite well.
The main thing to note is that the 'chr' attribute of a feature must
<em>exactly</em> match one of the headers in the fasta file.</p>
<div class="section" id="creation">
<h2><a class="toc-backref" href="#id12">Creation</a></h2>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">from</span> <span style="color: #0000FF; font-weight: bold">genedex</span> <span style="color: #008000; font-weight: bold">import</span> Fasta, Genedex
<span style="color: #666666">&gt;&gt;&gt;</span> f <span style="color: #666666">=</span> Fasta(<span style="color: #BA2121">&#39;tests/data/two_chrs.fasta&#39;</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> g <span style="color: #666666">=</span> Genedex(fasta<span style="color: #666666">=</span>f)

<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">for</span> i <span style="color: #AA22FF; font-weight: bold">in</span> <span style="color: #008000">range</span>(<span style="color: #666666">1</span>, <span style="color: #666666">31</span>, <span style="color: #666666">5</span>):
<span style="color: #666666">...</span>     strand  <span style="color: #666666">=</span> i <span style="color: #666666">%</span> <span style="color: #666666">2</span> <span style="color: #AA22FF; font-weight: bold">and</span> <span style="color: #666666">-1</span> <span style="color: #AA22FF; font-weight: bold">or</span> <span style="color: #666666">1</span>
<span style="color: #666666">...</span>     feature <span style="color: #666666">=</span> {<span style="color: #BA2121">&#39;start&#39;</span>: i, <span style="color: #BA2121">&#39;stop&#39;</span>: i <span style="color: #666666">+</span> <span style="color: #666666">5</span>
<span style="color: #666666">...</span>             , <span style="color: #BA2121">&#39;strand&#39;</span>: strand, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>}
<span style="color: #666666">...</span>     g<span style="color: #666666">.</span>append(feature)
</pre></div>
</div>
<div class="section" id="query">
<h2><a class="toc-backref" href="#id13">Query</a></h2>
<p>This will automatically return the reverse complement if strand == -1.</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> feature <span style="color: #666666">=</span> g[<span style="color: #666666">2</span>]
<span style="color: #666666">&gt;&gt;&gt;</span> feature
{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">11</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}

<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>neighbors(feature, direction<span style="color: #666666">=</span>g<span style="color: #666666">.</span>UP_STREAM)
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">21</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}]
<span style="color: #666666">&gt;&gt;&gt;</span> neighbors <span style="color: #666666">=</span> g<span style="color: #666666">.</span>neighbors(feature, direction<span style="color: #666666">=</span>g<span style="color: #666666">.</span>UP_STREAM, n<span style="color: #666666">=2</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> neighbors
[{<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">16</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">21</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">1</span>}, {<span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">21</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">26</span>, <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>}]
<span style="color: #666666">&gt;&gt;&gt;</span> [g<span style="color: #666666">.</span>sequence(n) <span style="color: #008000; font-weight: bold">for</span> n <span style="color: #AA22FF; font-weight: bold">in</span> neighbors]
[<span style="color: #BA2121">&#39;GACTGA&#39;</span>, <span style="color: #BA2121">&#39;GTCAGT&#39;</span>]
</pre></div>
</div>
<div class="section" id="exons">
<h2><a class="toc-backref" href="#id14">Exons</a></h2>
<p>Exons are just a list of (start, stop) tuples. And can be use to slice
out sequence.</p>
<div class="highlight"><pre><span style="color: #666666">&gt;&gt;&gt;</span> feature <span style="color: #666666">=</span> { <span style="color: #BA2121">&#39;name&#39;</span>: <span style="color: #BA2121">&#39;At2g26540&#39;</span>, <span style="color: #BA2121">&#39;start&#39;</span>: <span style="color: #666666">23</span>, <span style="color: #BA2121">&#39;stop&#39;</span>: <span style="color: #666666">67</span>
<span style="color: #666666">...</span>           , <span style="color: #BA2121">&#39;strand&#39;</span>: <span style="color: #666666">-1</span>, <span style="color: #BA2121">&#39;chr&#39;</span>: <span style="color: #BA2121">&#39;chr1&#39;</span>
<span style="color: #666666">...</span>           , <span style="color: #BA2121">&#39;exons&#39;</span>:[(<span style="color: #666666">23</span>, <span style="color: #666666">25</span>), (<span style="color: #666666">29</span>, <span style="color: #666666">37</span>), (<span style="color: #666666">49</span>, <span style="color: #666666">66</span>)]
<span style="color: #666666">...</span>           , <span style="color: #BA2121">&#39;mRNAs&#39;</span>:[(<span style="color: #666666">24</span>, <span style="color: #666666">26</span>), (<span style="color: #666666">28</span>, <span style="color: #666666">38</span>), (<span style="color: #666666">44</span>, <span style="color: #666666">55</span>)] }

<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>sequence(feature, exon_keys<span style="color: #666666">=</span>(<span style="color: #BA2121">&#39;exons&#39;</span>,))
<span style="color: #BA2121">&#39;GTCAGTCAGTCAGTCAGTTCAGTCAGTTCA&#39;</span>

<span style="color: #408080; font-style: italic"># it will iterate over exon_keys til it finds that key in the feature.</span>
<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>sequence(feature, exon_keys<span style="color: #666666">=</span>(<span style="color: #BA2121">&#39;frankenstein&#39;</span>, <span style="color: #BA2121">&#39;mRNAs&#39;</span>,))
<span style="color: #BA2121">&#39;AGTCAGTCAGTCGTCAGTCAGTCGTC&#39;</span>


<span style="color: #408080; font-style: italic"># if it cant find any of the exon keys it will default to the</span>
<span style="color: #408080; font-style: italic"># start, stop</span>
<span style="color: #666666">&gt;&gt;&gt;</span> g<span style="color: #666666">.</span>sequence(feature, exon_keys<span style="color: #666666">=</span>(<span style="color: #BA2121">&#39;FAKEZZZZ&#39;</span>,))
<span style="color: #BA2121">&#39;AGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCAGTCA&#39;</span>



<span style="color: #666666">&gt;&gt;&gt;</span> <span style="color: #008000; font-weight: bold">import</span> <span style="color: #0000FF; font-weight: bold">os</span> <span style="color: #408080; font-style: italic"># cleanup.</span>
<span style="color: #666666">&gt;&gt;&gt;</span> _ <span style="color: #666666">=</span> os<span style="color: #666666">.</span>unlink(<span style="color: #BA2121">&#39;/tmp/genedex_test.idx&#39;</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> _ <span style="color: #666666">=</span> os<span style="color: #666666">.</span>unlink(<span style="color: #BA2121">&#39;/tmp/genedex_test.pkl&#39;</span>)
<span style="color: #666666">&gt;&gt;&gt;</span> _ <span style="color: #666666">=</span> os<span style="color: #666666">.</span>unlink(<span style="color: #BA2121">&#39;/tmp/genedex_test.dat&#39;</span>)
</pre></div>
</div>
</div>
<div class="section" id="bugs">
<h1><a class="toc-backref" href="#id15">Bugs</a></h1>
<p>Currently, all features are stored in the same index regardless of
chromosome. So when querying, it will return features as neighbors
that are on different strands... The solution is to manually create a
separate genedex per chromosome.</p>
</div>
<div class="section" id="todo">
<h1><a class="toc-backref" href="#id16">TODO</a></h1>
<p>Potentially allow for sqlite/DBM backends as well as the pickle. This
would be nice, especially the sqlite backend as it would allow for
indexed queries on any attributes, but will increase code
complexity quite a bit -- and may make it difficult to keep using
dict()'s as the feature type...</p>
</div>
</div>
</body>
</html>
